.TH darkice 1 "August 27, 2001" "DarkIce" "DarkIce live audio streamer"
.SH NAME
darkice \- an icecast live audio streamer
.SH SYNOPSIS
.B darkice
[options] -c config.file
.SH DESCRIPTION
.PP
.B DarkIce
is an
.B IceCast
live audio streamer. It takes audio input from a
sound card, encodes it into mp3, and sends the stream to an
.B IceCast
server.

.B DarkIce
uses
.SM POSIX
real-time scheduling to keep up with sound card input.
.SM POSIX
real-time scheduling is only available if the program is run as root.
Therefore it is recommended that
.B DarkIce
is run as root.

.B DarkIce
uses the
.B Lame
mp3 encoder as a library to encode audio intput to mp3.

.SH OPTIONS
.TP
.BI "\-c " config.file
.br
.ns
.TP
.BI \-\-config= config.file
Specifies what configuration file to use.

.TP
.BI "\-v " n
.br
.ns
.TP
.BI \-\-verbosity= n
Sets the verbosity level, between 0 and 10. 0 is silent, 10 is loud.
Defaults to 1.

.TP
.BI "\-h "
.br
.ns
.TP
.BI \-\-help
Prints the help page and exists.


.SH "CONFIGURATION FILE"
.B DarkIce
needs a configuration file to operate.
The configuration file consists of sections, with key = value pairs
inside each secion:

.nf
[section1]
# this is a whole line comment
key = value
an ugly key name = long value    # this end is a comment too

[section2]
# this is a whole line comment in section 2
key = value
an ugly key name = long value    # this end is a comment too
.fi

In particular, the following sections and values are recognized:
.PP
.B [general]

This section describes general operational parameters (required).

Required values:

.TP
.I duration
Time for DarkIce to run, in seconds.  If 0, run forever.
.TP
.I bufferSecs
Data read from the sound card is buffered before sent to
the mp3 encoder. Each buffer will be able to hold this
many seconds of samples.

.PP
.B [input]

This section describes the input (required).

Required values:

.TP
.I device
OSS DSP audio device to record from (e.g. /dev/dsp)
.TP
.I sampleRate
The sample rate to record with, samples per second
(e.g. 44100 for 44.1kHz CD-quality audio, 22050 for 22kHz or 11025
for 11kHz)
.TP
.I bitsPerSample
Number of bits to use for each sample (e.g. 8 bits or 16 bits)
.TP
.I channel
Number of channels to record (e.g. 1 for mono, 2 for stereo)

.PP
.B [lamex]

This section describes an output to an
.B IceCast
server, while encoding
with a lame encoder. There may be at most 8 outputs, numbered from 0 ... 7.
The number is included in the section name (e.g. [lame0] ... [lame7]).
The stream will be reachable at
.I http://<server>:<port>/<mountPoint>
At least one such section is required.

Required values:

.TP
.I bitrate
Bit rate to encode to in kBits / sec (e.g. 96)
.TP
.I server
The
.B IceCast
server's name (e.g. yp.sourserver.com)
.TP
.I port
The port to connect to the IceCast server (e.g. 8000)
.TP
.I password
The password to use to connet to the
.B IceCast
server
.TP
.I mountPoint
Mount point for the stream on the server

.PP
Optional values:

.TP
.I name
Name of the stream
.TP
.I description
Description of the stream
.TP
.I url
Url related to the stream
.TP
.I genre
Genre of the stream
.TP
.I public
"yes" or "no", wether the stream is public
.TP
.I remoteDumpFile 
The file the
.B IceCast
server should dump the contents of
this stream on its side.
.TP
.I lowpass
Lowpass filter setting for the lame encoder. If not set,
the encoder's default behaviour is used
.TP
.I highpass
Highpass filter setting for the lame encoder. If not set,
the encoder's default behaviour is used

.PP
A sample configuration file follows. This file makes
.B DarkIce
stream for 1 minute (60 seconds) from the audio device
.I /dev/dsp
at 22kHz, 16 bit stereo.
It will build up a connection to the
.B IceCast
server yp.yourserver.com on port 8000 with the password "hackme".
The stream will be encoded to 96 kb/s mp3, and will be reachable at
.I http://yp.yourserver.com:8000/live96
to mp3 players.
The encoding session will be stored by
.B IceCast
in the file
.I /tmp/live96.mp3
on the server side.

.nf
[general]
duration        = 60
bufferSecs      = 5

[input]
device          = /dev/dsp
sampleRate      = 22050
bitsPerSample   = 16
channel         = 2

[lame0]
bitrate         = 96
server          = yp.yourserver.com
port            = 8000
password        = hackme
mountPoint      = live96
name            = DarkIce trial
description     = This is only a trial
url             = http://www.yourserver.com
genre           = live
public          = no
remoteDumpFile  = /tmp/live96.mp3
.fi


.SH BUGS
.PP
Lots of bugs.


.SH AUTHOR
Akos Maroy
.I <darkeye@users.sourceforge.net>


.SH ACKNOWLEDGEMENTS
Some contributions by Jim Crilly
.I <JCrilly@MSA.com>


.SH LINKS
Project homepage:
.I http://darkice.sourceforge.net/

.B IceCast
homepage:
.I http://www.icecast.org/

.B Lame
homepage:
.I http://www.mp3dev.org/mp3/

